/* Copyright 2007-2008 dnAnalytics Project.
 *
 * Contributors to this file:
 * Patrick van der Velde
 *
 * This file is part of dnAnalytics.  dnAnalytics is licensed under the 
 * Microsoft Public License. See License.txt for a complete copy of the
 * license.
 */

using System;

namespace dnAnalytics.LinearAlgebra.Solvers
{
    /// <summary>
    /// The base interface for classes that provide stop criteria for iterative calculations. 
    /// </summary>
    public interface IIterationStopCriterium : ICloneable
    {
        /// <summary>
        /// Determines the status of the iterative calculation based on the stop criteria stored
        /// by the current <c>IIterationStopCriterium</c>.
        /// </summary>
        /// <param name="iterationNumber">The number of iterations that have passed so far.</param>
        /// <param name="solutionVector">The vector containing the current solution values.</param>
        /// <param name="sourceVector">The right hand side vector.</param>
        /// <param name="residualVector">The vector containing the current residual vectors.</param>
        /// <returns>
        ///   An <c>ICalculationStatus</c> which indicates what the status of the iterative 
        ///   calculation is according to the current <c>IIterationStopCriterium</c>.
        /// </returns>
        /// <remarks>
        /// The individual stop criteria may internally track the progress of the calculation based
        /// on the invocation of this method. Therefore this method should only be called if the 
        /// calculation has moved forwards at least one step.
        /// </remarks>
        void DetermineStatus(int iterationNumber, Vector solutionVector, Vector sourceVector, Vector residualVector);

        /// <summary>
        /// Returns the current calculation status.
        /// </summary>
        /// <remarks>
        /// Note to implementers: <c>null</c> is not a legal value.
        /// </remarks>
        ICalculationStatus Status { get; }

        /// <summary>
        /// Resets the <c>IIterationStopCriterium</c> to the pre-calculation state.
        /// </summary>
        /// <remarks>
        /// Note to implementers: Invoking this method should not clear the user defined
        /// property values, only the state that is used to track the progress of the 
        /// calculation.
        /// </remarks>
        void ResetToPrecalculationState();

        /// <summary>
        /// Returns the <c>StopLevel</c> which indicates what sort of stop criterium this
        /// <c>IIterationStopCriterium</c> monitors.
        /// </summary>
        StopLevel StopLevel { get; }

        /// <summary>
        /// Clones the current <c>IIterationStopCriterium</c> and its settings.
        /// </summary>
        /// <returns>A new instance of the specific <c>IIterationStopCriterium</c>.</returns>
        new IIterationStopCriterium Clone();
    }
}
